---
title: "Key Rerolling"
description: "Rotate API keys while preserving their configuration and permissions"
---

## What is Key Rerolling?

Key rerolling (or key rotation) is the process of generating a new API key token while preserving all the configuration from an existing key. This is a critical security practice that allows you to regularly rotate credentials without disrupting your application's permissions or settings.

## Why Reroll Keys?

Key rerolling serves several important purposes:

- **Security Compliance**: Many security frameworks require regular credential rotation
- **Compromise Recovery**: Quickly replace keys that may have been exposed
- **Proactive Security**: Regularly rotate keys as a preventive measure
- **Graceful Migration**: Overlap periods allow zero-downtime key transitions

## How Key Rerolling Works

### What Gets Copied

When you reroll a key, the new key is an exact copy of the original in terms of configuration:

**Preserved Settings:**

- Permissions and RBAC roles
- Custom metadata fields
- Rate limiting rules
- Identity associations (for tracking usage across keys)
- Remaining credits balance
- Recovery/encryption settings
- API association

### What's New

The rerolled key gets fresh values for:

- Key ID (a new unique identifier)
- API key token (the actual secret)
- Creation timestamp

### What Happens to the Original Key

The original key remains active for a configurable grace period:

- You specify the `expiration` duration (in milliseconds)
- Set to `0` for immediate revocation
- Common grace periods: 1 hour (3600000ms), 24 hours (86400000ms), 7 days (604800000ms)

## Making a Reroll Request

To reroll a key, make a `POST` request to `/v2/keys.rerollKey`:

```bash
curl --request POST \
  --url https://api.unkey.com/v2/keys.rerollKey \
  --header 'Authorization: Bearer <ROOT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "expiration": 86400000
  }'
```

### Request Parameters

- `keyId` (required): The database identifier of the key to reroll (NOT the API key token)
- `expiration` (required): Duration in milliseconds until the original key is revoked

### Response

```json
{
  "meta": {
    "requestId": "req_abc123def456"
  },
  "data": {
    "keyId": "key_3dHLcNyRzJaiDyo2Jekz9r",
    "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
  }
}
```

<warning>
  **Security Critical**: The `key` field contains the actual API key token. This is the only time you'll receive it - Unkey stores only a hashed version. Never log or expose this value. Transmit it directly to the end user via secure channels only.
</warning>

## Common Use Cases

### Zero-Downtime Key Rotation

For production systems that can't afford downtime:

1. Reroll the key with a grace period (e.g., 24 hours)
2. Deploy the new key to your systems
3. Verify the new key is working
4. The old key automatically expires after the grace period

```bash
# Give 24 hours for migration
curl --request POST \
  --url https://api.unkey.com/v2/keys.rerollKey \
  --header 'Authorization: Bearer <ROOT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "expiration": 86400000
  }'
```

### Emergency Key Replacement

When a key is compromised and needs immediate revocation:

```bash
# Revoke immediately
curl --request POST \
  --url https://api.unkey.com/v2/keys.rerollKey \
  --header 'Authorization: Bearer <ROOT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "expiration": 0
  }'
```

## Analytics and Usage Tracking

An important aspect of key rerolling is that analytics remain consistent:

- **Key-level metrics**: Each key has its own usage statistics
- **Identity-level metrics**: If the original key has an identity, the new key inherits it
- This allows you to track usage across both individual keys and the overall identity
- Historical data from the original key remains accessible

## Required Permissions

Your root key needs the following permissions to reroll keys:

- `api.*.create_key` or `api.<api_id>.create_key`
- `api.*.encrypt_key` or `api.<api_id>.encrypt_key` (only when the original key is recoverable)

## Limitations

- The new key uses the API's default configuration for prefix and byte length
- You cannot modify permissions or settings during reroll - use the update endpoint afterward if needed